/**
 * Copyright 2008 Matthew Purland (m.purland@gmail.com)
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package org.variance.version.identifier;

/**
 * A source to retrieve a set of revision identifiers.
 *
 * This could be a manager to retrieve from database, local file, constant data,
 * etc.
 *
 * @author Matthew Purland
 */
public interface RevisionIdentifierSource {

    /**
     * Return whether there are any available identifiers.
     */
    boolean hasAvailableIdentifiers();

    /**
     * Get a newly available revision identifier.
     *
     * @return Returns null if there are no available identifiers, otherwise
     *         will return an available identifier from the source.
     */
    RevisionIdentifier getAvailableIdentifier();

    /**
     * Determine if the given revision identifier is the latest
     *
     * @return True if the given revision identifier is the latest; false otherwise.
     */
    boolean isLatest(RevisionIdentifier revisionIdentifier);

    /**
     * Remove an existing revision identifier
     *
     * @return Returns successfully if the existing identifer was successfully
     *         removed. TODO Add exception
     */
    void removeIdentifier(RevisionIdentifier identifier);

    /**
     * Add an identifier to this identifier source TODO Add exception
     */
    void addIdentifier(RevisionIdentifier identifier);

}
